<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width">
<meta name="generator" content="Docusaurus v2.0.0-alpha.54">
<link rel="preconnect" href="https://www.google-analytics.com">
<script>window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)},ga.l=+new Date,ga("create","UA-128126650-1","auto"),ga("send","pageview")</script>
<script async src="https://www.google-analytics.com/analytics.js"></script>
<link rel="preconnect" href="https://www.google-analytics.com">
<link rel="preconnect" href="https://www.googletagmanager.com">
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-128126650-1"></script>
<script>function gtag(){dataLayer.push(arguments)}window.dataLayer=window.dataLayer||[],gtag("js",new Date),gtag("config","UA-128126650-1",{})</script>
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Poppins:ital,wght@0,400;0,700;1,400&family=Roboto:wght@900&display=swap">

<title data-react-helmet="true">Vinyl | gulp.js</title>

<meta data-react-helmet="true" name="twitter:card" content="summary_large_image"><meta data-react-helmet="true" property="og:title" content="Vinyl | gulp.js"><meta data-react-helmet="true" name="description" content="# Vinyl"><meta data-react-helmet="true" property="og:description" content="# Vinyl"><meta data-react-helmet="true" property="og:url" content="https://gulpjs.com//docs/en/api/vinyl">

<link data-react-helmet="true" rel="shortcut icon" href="/img/favicon.png">


<link rel="stylesheet" href="/styles.8121b95c.css">


<link rel="preload" href="/styles.10c0193b.js" as="script">

<link rel="preload" href="/runtime~main.ae01ffbb.js" as="script">

<link rel="preload" href="/main.3e1928f1.js" as="script">

<link rel="preload" href="/1.fe6bacd8.js" as="script">

<link rel="preload" href="/2.77a8f44b.js" as="script">

<link rel="preload" href="/1be78505.2d41add8.js" as="script">

<link rel="preload" href="/37.ee8d4ee9.js" as="script">

<link rel="preload" href="/10002e1b.63b80d46.js" as="script">

<link rel="preload" href="/17896441.f1e2ba83.js" as="script">

<link rel="preload" href="/c360a4e4.fdefb763.js" as="script">

</head>
<body>

<div id="__docusaurus">
<nav class="navbar navbar--light navbar--fixed-top"><div class="navbar__inner"><div class="navbar__items"><a class="navbar__brand" target="_self" href="/"><img class="navbar__logo" src="/img/gulp.svg" alt="gulp"></a><a activeclassname="navbar__link--active" class="navbar__item navbar__link noWrap_BxdH" href="/docs/en/getting-started/quick-start">Get Started</a><a activeclassname="navbar__link--active" class="navbar__item navbar__link noWrap_BxdH" href="/docs/en/api/concepts">API</a><a activeclassname="navbar__link--active" class="navbar__item navbar__link noWrap_BxdH" href="/plugins">Plugins</a><a target="_blank" rel="noopener noreferrer" href="https://github.com/sponsors/gulpjs" class="navbar__item navbar__link noWrap_BxdH">Donate</a><a activeclassname="navbar__link--active" class="navbar__item navbar__link emphasis_1Gl9 noWrap_BxdH" href="/docs/en/support/for-enterprise">Enterprise</a></div><div class="navbar__items navbar__items--right"><a target="_blank" rel="noopener noreferrer" href="https://twitter.com/gulpjs" class="navbar__item navbar__link navbar__link--icon noWrap_BxdH"><img class="navbarIcon_2_MD" src="/img/twitter.svg" alt="Gulp on Twitter"></a><a target="_blank" rel="noopener noreferrer" href="https://medium.com/gulpjs" class="navbar__item navbar__link navbar__link--icon noWrap_BxdH"><img class="navbarIcon_2_MD" src="/img/medium.svg" alt="The gulp blog"></a><div class="navbar__search"><span aria-label="expand searchbar" role="button" class="search-icon search-icon-hidden" tabindex="0"></span><input type="search" id="search_input_react" placeholder="Search" aria-label="Search" class="navbar__search-input search-bar-expanded"></div></div></div></nav><div class="main-wrapper"><div class="docPage_1kjD"><div class="docSidebarContainer_1cYp"><div class="sidebar_1kLs"><div class="menu menu--responsive menu_w2sC"><button aria-label="Open Menu" aria-haspopup="true" class="button button--secondary button--sm menu__button" type="button"><svg aria-label="Menu" class="sidebarMenuIcon_2vk4" xmlns="http://www.w3.org/2000/svg" height="24" width="24" viewBox="0 0 32 32" role="img" focusable="false"><title>Menu</title><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></button><ul class="menu__list"><li class="menu__list-item menu__list-item--collapsed"><a class="menu__link menu__link--sublist" href="#!">Getting Started</a><ul class="menu__list"><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/en/getting-started/quick-start">Quick Start</a></li><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/en/getting-started/javascript-and-gulpfiles">JavaScript and Gulpfiles</a></li><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/en/getting-started/creating-tasks">Creating Tasks</a></li><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/en/getting-started/async-completion">Async Completion</a></li><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/en/getting-started/working-with-files">Working with Files</a></li><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/en/getting-started/explaining-globs">Explaining Globs</a></li><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/en/getting-started/using-plugins">Using Plugins</a></li><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/en/getting-started/watching-files">Watching Files</a></li></ul></li><li class="menu__list-item"><a class="menu__link menu__link--sublist menu__link--active" href="#!">API</a><ul class="menu__list"><li class="menu__list-item"><a class="menu__link" tabindex="0" href="/docs/en/api/concepts">Concepts</a></li><li class="menu__list-item"><a class="menu__link" tabindex="0" href="/docs/en/api/src">src()</a></li><li class="menu__list-item"><a class="menu__link" tabindex="0" href="/docs/en/api/dest">dest()</a></li><li class="menu__list-item"><a class="menu__link" tabindex="0" href="/docs/en/api/symlink">symlink()</a></li><li class="menu__list-item"><a class="menu__link" tabindex="0" href="/docs/en/api/lastrun">lastRun()</a></li><li class="menu__list-item"><a class="menu__link" tabindex="0" href="/docs/en/api/series">series()</a></li><li class="menu__list-item"><a class="menu__link" tabindex="0" href="/docs/en/api/parallel">parallel()</a></li><li class="menu__list-item"><a class="menu__link" tabindex="0" href="/docs/en/api/watch">watch()</a></li><li class="menu__list-item"><a class="menu__link" tabindex="0" href="/docs/en/api/task">task()</a></li><li class="menu__list-item"><a class="menu__link" tabindex="0" href="/docs/en/api/registry">registry()</a></li><li class="menu__list-item"><a class="menu__link" tabindex="0" href="/docs/en/api/tree">tree()</a></li><li class="menu__list-item"><a aria-current="page" class="menu__link menu__link--active" tabindex="0" href="/docs/en/api/vinyl">Vinyl</a></li><li class="menu__list-item"><a class="menu__link" tabindex="0" href="/docs/en/api/vinyl-isvinyl">Vinyl.isVinyl()</a></li><li class="menu__list-item"><a class="menu__link" tabindex="0" href="/docs/en/api/vinyl-iscustomprop">Vinyl.isCustomProp()</a></li></ul></li><li class="menu__list-item menu__list-item--collapsed"><a class="menu__link menu__link--sublist" href="#!">Support</a><ul class="menu__list"><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/en/support/for-enterprise">For Enterprise</a></li></ul></li></ul></div></div></div><main class="docMainContainer_FFX1"><div class="container padding-vert--lg docItemWrapper_1cc7"><div class="row"><div class="col docItemCol_2GOA"><div class="docItemContainer_2cwg"><article><div class="markdown"><h1><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_ZqCz" id="vinyl"></a><a aria-hidden="true" tabindex="-1" class="hash-link" href="#vinyl" title="Direct link to heading">#</a>Vinyl</h1><p>A virtual file format. When a file is read by <code>src()</code>, a Vinyl object is generated to represent the file - including the path, contents, and other metadata.</p><p>Vinyl objects can have transformations applied using <a href="/docs/en/getting-started/using-plugins">plugins</a>. They may also be persisted to the file system using <code>dest()</code>.</p><p>When creating your own Vinyl objects - instead of generating with <code>src()</code> - use the external <code>vinyl</code> module, as shown in Usage below.</p><h2><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_ZqCz" id="usage"></a><a aria-hidden="true" tabindex="-1" class="hash-link" href="#usage" title="Direct link to heading">#</a>Usage</h2><div class="mdxCodeBlock_iHAB"><div class="codeBlockContent_32p_"><button type="button" aria-label="Copy code to clipboard" class="copyButton_1BYj">Copy</button><div tabindex="0" class="prism-code language-js codeBlock_19pQ"><div class="codeBlockLines_2n9r" style="color:#9CDCFE;background-color:#1E1E1E"><div class="token-line" style="color:#9CDCFE"><span class="token keyword" style="color:rgb(86, 156, 214)">const</span><span class="token plain"> </span><span class="token maybe-class-name">Vinyl</span><span class="token plain"> </span><span class="token operator" style="color:rgb(212, 212, 212)">=</span><span class="token plain"> </span><span class="token function" style="color:rgb(220, 220, 170)">require</span><span class="token punctuation" style="color:rgb(212, 212, 212)">(</span><span class="token string" style="color:rgb(206, 145, 120)">&#x27;vinyl&#x27;</span><span class="token punctuation" style="color:rgb(212, 212, 212)">)</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><span class="token plain"></span></div><div class="token-line" style="color:#9CDCFE"><span class="token plain" style="display:inline-block">
</span></div><div class="token-line" style="color:#9CDCFE"><span class="token plain"></span><span class="token keyword" style="color:rgb(86, 156, 214)">const</span><span class="token plain"> file </span><span class="token operator" style="color:rgb(212, 212, 212)">=</span><span class="token plain"> </span><span class="token keyword" style="color:rgb(86, 156, 214)">new</span><span class="token plain"> </span><span class="token class-name" style="color:rgb(78, 201, 176)">Vinyl</span><span class="token punctuation" style="color:rgb(212, 212, 212)">(</span><span class="token punctuation" style="color:rgb(212, 212, 212)">{</span><span class="token plain"></span></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">  cwd</span><span class="token operator" style="color:rgb(212, 212, 212)">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(206, 145, 120)">&#x27;/&#x27;</span><span class="token punctuation" style="color:rgb(212, 212, 212)">,</span><span class="token plain"></span></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">  base</span><span class="token operator" style="color:rgb(212, 212, 212)">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(206, 145, 120)">&#x27;/test/&#x27;</span><span class="token punctuation" style="color:rgb(212, 212, 212)">,</span><span class="token plain"></span></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">  path</span><span class="token operator" style="color:rgb(212, 212, 212)">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(206, 145, 120)">&#x27;/test/file.js&#x27;</span><span class="token punctuation" style="color:rgb(212, 212, 212)">,</span><span class="token plain"></span></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">  contents</span><span class="token operator" style="color:rgb(212, 212, 212)">:</span><span class="token plain"> </span><span class="token keyword" style="color:rgb(86, 156, 214)">new</span><span class="token plain"> </span><span class="token class-name" style="color:rgb(78, 201, 176)">Buffer</span><span class="token punctuation" style="color:rgb(212, 212, 212)">(</span><span class="token string" style="color:rgb(206, 145, 120)">&#x27;var x = 123&#x27;</span><span class="token punctuation" style="color:rgb(212, 212, 212)">)</span><span class="token plain"></span></div><div class="token-line" style="color:#9CDCFE"><span class="token plain"></span><span class="token punctuation" style="color:rgb(212, 212, 212)">}</span><span class="token punctuation" style="color:rgb(212, 212, 212)">)</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><span class="token plain"></span></div><div class="token-line" style="color:#9CDCFE"><span class="token plain" style="display:inline-block">
</span></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">file</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token property-access">relative</span><span class="token plain"> </span><span class="token operator" style="color:rgb(212, 212, 212)">===</span><span class="token plain"> </span><span class="token string" style="color:rgb(206, 145, 120)">&#x27;file.js&#x27;</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><span class="token plain"></span></div><div class="token-line" style="color:#9CDCFE"><span class="token plain" style="display:inline-block">
</span></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">file</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token property-access">dirname</span><span class="token plain"> </span><span class="token operator" style="color:rgb(212, 212, 212)">===</span><span class="token plain"> </span><span class="token string" style="color:rgb(206, 145, 120)">&#x27;/test&#x27;</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><span class="token plain"></span></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">file</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token property-access">dirname</span><span class="token plain"> </span><span class="token operator" style="color:rgb(212, 212, 212)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(206, 145, 120)">&#x27;/specs&#x27;</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><span class="token plain"></span></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">file</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token property-access">path</span><span class="token plain"> </span><span class="token operator" style="color:rgb(212, 212, 212)">===</span><span class="token plain"> </span><span class="token string" style="color:rgb(206, 145, 120)">&#x27;/specs/file.js&#x27;</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><span class="token plain"></span></div><div class="token-line" style="color:#9CDCFE"><span class="token plain" style="display:inline-block">
</span></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">file</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token property-access">basename</span><span class="token plain"> </span><span class="token operator" style="color:rgb(212, 212, 212)">===</span><span class="token plain"> </span><span class="token string" style="color:rgb(206, 145, 120)">&#x27;file.js&#x27;</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><span class="token plain"></span></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">file</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token property-access">basename</span><span class="token plain"> </span><span class="token operator" style="color:rgb(212, 212, 212)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(206, 145, 120)">&#x27;file.txt&#x27;</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><span class="token plain"></span></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">file</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token property-access">path</span><span class="token plain"> </span><span class="token operator" style="color:rgb(212, 212, 212)">===</span><span class="token plain"> </span><span class="token string" style="color:rgb(206, 145, 120)">&#x27;/specs/file.txt&#x27;</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><span class="token plain"></span></div><div class="token-line" style="color:#9CDCFE"><span class="token plain" style="display:inline-block">
</span></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">file</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token property-access">stem</span><span class="token plain"> </span><span class="token operator" style="color:rgb(212, 212, 212)">===</span><span class="token plain"> </span><span class="token string" style="color:rgb(206, 145, 120)">&#x27;file&#x27;</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><span class="token plain"></span></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">file</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token property-access">stem</span><span class="token plain"> </span><span class="token operator" style="color:rgb(212, 212, 212)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(206, 145, 120)">&#x27;foo&#x27;</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><span class="token plain"></span></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">file</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token property-access">path</span><span class="token plain"> </span><span class="token operator" style="color:rgb(212, 212, 212)">===</span><span class="token plain"> </span><span class="token string" style="color:rgb(206, 145, 120)">&#x27;/specs/foo.txt&#x27;</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><span class="token plain"></span></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">file</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token property-access">extname</span><span class="token plain"> </span><span class="token operator" style="color:rgb(212, 212, 212)">===</span><span class="token plain"> </span><span class="token string" style="color:rgb(206, 145, 120)">&#x27;.txt&#x27;</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><span class="token plain"></span></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">file</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token property-access">extname</span><span class="token plain"> </span><span class="token operator" style="color:rgb(212, 212, 212)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(206, 145, 120)">&#x27;.js&#x27;</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><span class="token plain"></span></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">file</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token property-access">path</span><span class="token plain"> </span><span class="token operator" style="color:rgb(212, 212, 212)">===</span><span class="token plain"> </span><span class="token string" style="color:rgb(206, 145, 120)">&#x27;/specs/foo.js&#x27;</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span></div></div></div></div></div><h2><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_ZqCz" id="signature"></a><a aria-hidden="true" tabindex="-1" class="hash-link" href="#signature" title="Direct link to heading">#</a>Signature</h2><div class="mdxCodeBlock_iHAB"><div class="codeBlockContent_32p_"><button type="button" aria-label="Copy code to clipboard" class="copyButton_1BYj">Copy</button><div tabindex="0" class="prism-code language-js codeBlock_19pQ"><div class="codeBlockLines_2n9r" style="color:#9CDCFE;background-color:#1E1E1E"><div class="token-line" style="color:#9CDCFE"><span class="token keyword" style="color:rgb(86, 156, 214)">new</span><span class="token plain"> </span><span class="token class-name" style="color:rgb(78, 201, 176)">Vinyl</span><span class="token punctuation" style="color:rgb(212, 212, 212)">(</span><span class="token punctuation" style="color:rgb(212, 212, 212)">[</span><span class="token plain">options</span><span class="token punctuation" style="color:rgb(212, 212, 212)">]</span><span class="token punctuation" style="color:rgb(212, 212, 212)">)</span></div></div></div></div></div><h3><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_ZqCz" id="parameters"></a><a aria-hidden="true" tabindex="-1" class="hash-link" href="#parameters" title="Direct link to heading">#</a>Parameters</h3><table><thead><tr><th align="center">parameter</th><th align="center">type</th><th>note</th></tr></thead><tbody><tr><td align="center">options</td><td align="center">object</td><td>Detailed in <a href="#options">Options</a> below.</td></tr></tbody></table><h3><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_ZqCz" id="returns"></a><a aria-hidden="true" tabindex="-1" class="hash-link" href="#returns" title="Direct link to heading">#</a>Returns</h3><p>An instance of the Vinyl class representing a single virtual file, detailed in <a href="#vinyl-instance">Vinyl instance</a> below.</p><h3><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_ZqCz" id="errors"></a><a aria-hidden="true" tabindex="-1" class="hash-link" href="#errors" title="Direct link to heading">#</a>Errors</h3><p>When any passed options don&#x27;t conform to the <a href="#instance-properties">instance property definitions</a> (like if <code>path</code> is set to a number) throws as defined in the table.</p><h3><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_ZqCz" id="options"></a><a aria-hidden="true" tabindex="-1" class="hash-link" href="#options" title="Direct link to heading">#</a>Options</h3><table><thead><tr><th align="center">name</th><th align="center">type</th><th>default</th><th>note</th></tr></thead><tbody><tr><td align="center">cwd</td><td align="center">string</td><td><code>process.cwd()</code></td><td>The directory from which relative paths will be derived. Will be <a href="#normalization-and-concatenation">normalized</a> and have trailing separators removed.</td></tr><tr><td align="center">base</td><td align="center">string</td><td></td><td>Used to calculate the <code>relative</code> instance property. Falls back to the value of <code>cwd</code> if not set. Typically set to the <a href="/docs/en/api/concepts#glob-base">glob base</a>. Will be <a href="#normalization-and-concatenation">normalized</a> and have trailing separators removed.</td></tr><tr><td align="center">path</td><td align="center">string</td><td></td><td>The full, absolute file path. Will be <a href="#normalization-and-concatenation">normalized</a> and have trailing separators removed.</td></tr><tr><td align="center">history</td><td align="center">array</td><td><code>[ ]</code></td><td>An array of paths to pre-populate the <code>history</code> of a Vinyl instance. Usually comes from deriving a new Vinyl object from a previous Vinyl object. If <code>path</code> and <code>history</code> are both passed, <code>path</code> is appended to <code>history</code>. Each item will be <a href="#normalization-and-concatenation">normalized</a> and have trailing separators removed.</td></tr><tr><td align="center">stat</td><td align="center">object</td><td></td><td>An instance of <code>fs.Stats</code>, usually the result of calling <code>fs.stat()</code> on a file. Used to determine if a Vinyl object represents a directory or symbolic link.</td></tr><tr><td align="center">contents</td><td align="center">ReadableStream<br>Buffer<br><code>null</code></td><td><code>null</code></td><td>The contents of the file. If <code>contents</code> is a ReadableStream, it is wrapped in a <a href="https://github.com/mcollina/cloneable-readable">cloneable-readable</a> stream.</td></tr></tbody></table><p>Any other properties on <code>options</code> will be directly assigned to the Vinyl instance.</p><div class="mdxCodeBlock_iHAB"><div class="codeBlockContent_32p_"><button type="button" aria-label="Copy code to clipboard" class="copyButton_1BYj">Copy</button><div tabindex="0" class="prism-code language-js codeBlock_19pQ"><div class="codeBlockLines_2n9r" style="color:#9CDCFE;background-color:#1E1E1E"><div class="token-line" style="color:#9CDCFE"><span class="token keyword" style="color:rgb(86, 156, 214)">const</span><span class="token plain"> </span><span class="token maybe-class-name">Vinyl</span><span class="token plain"> </span><span class="token operator" style="color:rgb(212, 212, 212)">=</span><span class="token plain"> </span><span class="token function" style="color:rgb(220, 220, 170)">require</span><span class="token punctuation" style="color:rgb(212, 212, 212)">(</span><span class="token string" style="color:rgb(206, 145, 120)">&#x27;vinyl&#x27;</span><span class="token punctuation" style="color:rgb(212, 212, 212)">)</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><span class="token plain"></span></div><div class="token-line" style="color:#9CDCFE"><span class="token plain" style="display:inline-block">
</span></div><div class="token-line" style="color:#9CDCFE"><span class="token plain"></span><span class="token keyword" style="color:rgb(86, 156, 214)">const</span><span class="token plain"> file </span><span class="token operator" style="color:rgb(212, 212, 212)">=</span><span class="token plain"> </span><span class="token keyword" style="color:rgb(86, 156, 214)">new</span><span class="token plain"> </span><span class="token class-name" style="color:rgb(78, 201, 176)">Vinyl</span><span class="token punctuation" style="color:rgb(212, 212, 212)">(</span><span class="token punctuation" style="color:rgb(212, 212, 212)">{</span><span class="token plain"> foo</span><span class="token operator" style="color:rgb(212, 212, 212)">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(206, 145, 120)">&#x27;bar&#x27;</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(212, 212, 212)">}</span><span class="token punctuation" style="color:rgb(212, 212, 212)">)</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><span class="token plain"></span></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">file</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token property-access">foo</span><span class="token plain"> </span><span class="token operator" style="color:rgb(212, 212, 212)">===</span><span class="token plain"> </span><span class="token string" style="color:rgb(206, 145, 120)">&#x27;bar&#x27;</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span></div></div></div></div></div><h2><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_ZqCz" id="vinyl-instance"></a><a aria-hidden="true" tabindex="-1" class="hash-link" href="#vinyl-instance" title="Direct link to heading">#</a>Vinyl instance</h2><p>Each instance of a Vinyl object will have properties and methods to access and/or modify information about the virtual file.</p><h3><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_ZqCz" id="instance-properties"></a><a aria-hidden="true" tabindex="-1" class="hash-link" href="#instance-properties" title="Direct link to heading">#</a>Instance properties</h3><p>All internally managed paths - any instance property except <code>contents</code> and <code>stat</code> - are normalized and have trailing separators removed. See <a href="#normalization-and-concatenation">Normalization and concatenation</a> for more information.</p><table><thead><tr><th align="center">property</th><th align="center">type</th><th>description</th><th>throws</th></tr></thead><tbody><tr><td align="center">contents</td><td align="center">ReadableStream<br>Buffer<br><code>null</code></td><td>Gets and sets the contents of the virtual file. If set to a ReadableStream, it is wrapped in a <a href="https://github.com/mcollina/cloneable-readable">cloneable-readable</a> stream.</td><td>If set to any value other than a ReadableStream, a Buffer, or <code>null</code>.</td></tr><tr><td align="center">stat</td><td align="center">object</td><td>Gets and sets an instance of <a href="/docs/en/api/concepts#file-system-stats"><code>fs.Stats</code></a>. Used when determining if a Vinyl object represents a directory or symbolic link.</td><td></td></tr><tr><td align="center">cwd</td><td align="center">string</td><td>Gets and sets the current working directory. Used for deriving relative paths.</td><td>If set to an empty string or any non-string value.</td></tr><tr><td align="center">base</td><td align="center">string</td><td>Gets and sets the base directory. Used to calculate the <code>relative</code> instance property. On a Vinyl object generated by <code>src()</code> will be set to the <a href="/docs/en/api/concepts#glob-base">glob base</a>. If set to <code>null</code> or <code>undefined</code>, falls back to the value of the <code>cwd</code> instance property.</td><td>If set to an empty string or any non-string value (except <code>null</code> or <code>undefined</code>).</td></tr><tr><td align="center">path</td><td align="center">string</td><td>Gets and sets the full, absolute file path. Setting to a value different from the current <code>path</code> appends the new path to the <code>history</code> instance property.</td><td>If set to any non-string value.</td></tr><tr><td align="center">history</td><td align="center">array</td><td>Array of all <code>path</code> values the Vinyl object has been assigned. The first element is the original path and the last element is the current path. This property and its elements should be treated as read-only and only altered indirectly by setting the <code>path</code> instance property.</td><td></td></tr><tr><td align="center">relative</td><td align="center">string</td><td>Gets the relative path segment between the <code>base</code> and the <code>path</code> instance properties.</td><td>If set to any value. If accessed when <code>path</code> is not available.</td></tr><tr><td align="center">dirname</td><td align="center">string</td><td>Gets and sets the directory of the <code>path</code> instance property.</td><td>If accessed when <code>path</code> is not available.</td></tr><tr><td align="center">stem</td><td align="center">string</td><td>Gets and sets the stem (filename without extension) of the <code>path</code> instance property.</td><td>If accessed when <code>path</code> is not available.</td></tr><tr><td align="center">extname</td><td align="center">string</td><td>Gets and sets the extension of the <code>path</code> instance property.</td><td>If accessed when <code>path</code> is not available.</td></tr><tr><td align="center">basename</td><td align="center">string</td><td>Gets and sets the filename (<code>stem + extname</code>) of the <code>path</code> instance property.</td><td>If accessed when <code>path</code> is not available.</td></tr><tr><td align="center">symlink</td><td align="center">string</td><td>Gets and sets the reference path of a symbolic link.</td><td>If set to any non-string value.</td></tr></tbody></table><h3><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_ZqCz" id="instance-methods"></a><a aria-hidden="true" tabindex="-1" class="hash-link" href="#instance-methods" title="Direct link to heading">#</a>Instance methods</h3><table><thead><tr><th align="center">method</th><th align="center">return type</th><th>returns</th></tr></thead><tbody><tr><td align="center"><code>isBuffer()</code></td><td align="center">boolean</td><td>If the <code>contents</code> instance property is a Buffer, returns true.</td></tr><tr><td align="center"><code>isStream()</code></td><td align="center">boolean</td><td>If the <code>contents</code> instance property is a Stream, returns true.</td></tr><tr><td align="center"><code>isNull()</code></td><td align="center">boolean</td><td>If the <code>contents</code> instance property is <code>null</code>, returns true.</td></tr><tr><td align="center"><code>isDirectory()</code></td><td align="center">boolean</td><td>If the instance represents a directory, returns true. An instance is considered a directory when <code>isNull()</code> returns true, the <code>stat</code> instance property is an object, and <code>stat.isDirectory()</code> returns true. This assumes a Vinyl object was constructed with a valid (or properly mocked) <code>fs.Stats</code> object.</td></tr><tr><td align="center"><code>isSymbolic()</code></td><td align="center">boolean</td><td>If the instance represents a symbolic link, returns true. An instance is considered symbolic when <code>isNull()</code> returns true, the <code>stat</code> instance property is an object, and <code>stat.isSymbolicLink()</code> returns true. This assumes a Vinyl object was constructed with a valid (or properly mocked) <code>fs.Stats</code> object.</td></tr><tr><td align="center"><code>clone([options])</code></td><td align="center">object</td><td>A new Vinyl object with all properties cloned. By default custom properties are deep cloned. If the <code>deep</code> option is false, custom attributes will be shallow cloned. If the <code>contents</code> option is false and the <code>contents</code> instance property is a Buffer, the Buffer will be reused instead of cloned.</td></tr><tr><td align="center"><code>inspect()</code></td><td align="center">string</td><td>Returns a formatted interpretation of the Vinyl object. Automatically called by Node&#x27;s console.log.</td></tr></tbody></table><h2><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_ZqCz" id="normalization-and-concatenation"></a><a aria-hidden="true" tabindex="-1" class="hash-link" href="#normalization-and-concatenation" title="Direct link to heading">#</a>Normalization and concatenation</h2><p>All path properties are normalized by their setters. Concatenate paths with <code>/</code>, instead of using <code>path.join()</code>, and normalization will occur properly on all platforms. Never concatenate with <code>\</code> - it  is a valid filename character on POSIX system.</p><div class="mdxCodeBlock_iHAB"><div class="codeBlockContent_32p_"><button type="button" aria-label="Copy code to clipboard" class="copyButton_1BYj">Copy</button><div tabindex="0" class="prism-code language-js codeBlock_19pQ"><div class="codeBlockLines_2n9r" style="color:#9CDCFE;background-color:#1E1E1E"><div class="token-line" style="color:#9CDCFE"><span class="token keyword" style="color:rgb(86, 156, 214)">const</span><span class="token plain"> file </span><span class="token operator" style="color:rgb(212, 212, 212)">=</span><span class="token plain"> </span><span class="token keyword" style="color:rgb(86, 156, 214)">new</span><span class="token plain"> </span><span class="token class-name" style="color:rgb(78, 201, 176)">File</span><span class="token punctuation" style="color:rgb(212, 212, 212)">(</span><span class="token punctuation" style="color:rgb(212, 212, 212)">)</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><span class="token plain"></span></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">file</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token property-access">path</span><span class="token plain"> </span><span class="token operator" style="color:rgb(212, 212, 212)">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(206, 145, 120)">&#x27;/&#x27;</span><span class="token plain"> </span><span class="token operator" style="color:rgb(212, 212, 212)">+</span><span class="token plain"> </span><span class="token string" style="color:rgb(206, 145, 120)">&#x27;test&#x27;</span><span class="token plain"> </span><span class="token operator" style="color:rgb(212, 212, 212)">+</span><span class="token plain"> </span><span class="token string" style="color:rgb(206, 145, 120)">&#x27;/&#x27;</span><span class="token plain"> </span><span class="token operator" style="color:rgb(212, 212, 212)">+</span><span class="token plain"> </span><span class="token string" style="color:rgb(206, 145, 120)">&#x27;foo.bar&#x27;</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><span class="token plain"></span></div><div class="token-line" style="color:#9CDCFE"><span class="token plain" style="display:inline-block">
</span></div><div class="token-line" style="color:#9CDCFE"><span class="token plain"></span><span class="token console class-name" style="color:rgb(78, 201, 176)">console</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token method function property-access" style="color:rgb(220, 220, 170)">log</span><span class="token punctuation" style="color:rgb(212, 212, 212)">(</span><span class="token plain">file</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token property-access">path</span><span class="token punctuation" style="color:rgb(212, 212, 212)">)</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><span class="token plain"></span></div><div class="token-line" style="color:#9CDCFE"><span class="token plain"></span><span class="token comment" style="color:rgb(106, 153, 85)">// posix =&gt; /test/foo.bar</span><span class="token plain"></span></div><div class="token-line" style="color:#9CDCFE"><span class="token plain"></span><span class="token comment" style="color:rgb(106, 153, 85)">// win32 =&gt; \\test\\foo.bar</span></div></div></div></div></div></div></article><div class="margin-vert--lg"><nav class="pagination-nav"><div class="pagination-nav__item"><a class="pagination-nav__link" href="/docs/en/api/tree"><div class="pagination-nav__link--sublabel">Previous</div><div class="pagination-nav__link--label">« tree()</div></a></div><div class="pagination-nav__item pagination-nav__item--next"><a class="pagination-nav__link" href="/docs/en/api/vinyl-isvinyl"><div class="pagination-nav__link--sublabel">Next</div><div class="pagination-nav__link--label">Vinyl.isVinyl() »</div></a></div></nav></div></div></div><div class="col col--3"><div class="tableOfContents_TbNY"><ul class="contents contents__left-border"><li><a href="#usage" class="contents__link">Usage</a></li><li><a href="#signature" class="contents__link">Signature</a><ul><li><a href="#parameters" class="contents__link">Parameters</a></li><li><a href="#returns" class="contents__link">Returns</a></li><li><a href="#errors" class="contents__link">Errors</a></li><li><a href="#options" class="contents__link">Options</a></li></ul></li><li><a href="#vinyl-instance" class="contents__link">Vinyl instance</a><ul><li><a href="#instance-properties" class="contents__link">Instance properties</a></li><li><a href="#instance-methods" class="contents__link">Instance methods</a></li></ul></li><li><a href="#normalization-and-concatenation" class="contents__link">Normalization and concatenation</a></li></ul></div></div></div></div></main></div></div><footer class="footer"><div class="container"><div class="row footer__links"><div class="col footer__col"><ul class="footer__items"><li class="footer__item"><img src="/img/gulp-white-logo.svg" alt="gulp" href="/"></li></ul></div><div class="col footer__col"><h4 class="footer__title">Docs</h4><ul class="footer__items"><li class="footer__item"><a class="footer__link-item" href="/docs/en/getting-started/quick-start">Getting Started</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/en/api/concepts">API</a></li></ul></div><div class="col footer__col"><h4 class="footer__title">Community</h4><ul class="footer__items"><li class="footer__item"><a class="footer__link-item" target="_blank" rel="noopener noreferrer" href="https://github.com/gulpjs/gulp">GitHub</a></li><li class="footer__item"><a class="footer__link-item" target="_blank" rel="noopener noreferrer" href="https://stackoverflow.com/questions/tagged/gulp">Stack Overflow</a></li><li class="footer__item"><a class="footer__link-item" target="_blank" rel="noopener noreferrer" href="https://twitter.com/gulpjs">Twitter</a></li></ul></div></div><div class="text--center"><div></div></div></div></footer>
</div>

<script src="/styles.10c0193b.js"></script>

<script src="/runtime~main.ae01ffbb.js"></script>

<script src="/main.3e1928f1.js"></script>

<script src="/1.fe6bacd8.js"></script>

<script src="/2.77a8f44b.js"></script>

<script src="/1be78505.2d41add8.js"></script>

<script src="/37.ee8d4ee9.js"></script>

<script src="/10002e1b.63b80d46.js"></script>

<script src="/17896441.f1e2ba83.js"></script>

<script src="/c360a4e4.fdefb763.js"></script>


</body>
</html>